fix(wgc): GPU DXGI encode path for Windows capture, with a fallback at every step - #305

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

The "shared keyed-mutex texture" is not a fallback point. All three places state that the GPU path degrades to the CPU path when the shared keyed-mutex texture is unavailable. It does not. MFEncoder::convertBgraTextureToNv12 creates that texture on the first frame (electron/native/wgc-capture/src/mf_encoder.cpp lines 941-994), after initialize() already configured the sink writer for NV12, so a failure there fails the recording. Either move the bridge creation into initializeDxgiPipeline() as proposed on electron/native/wgc-capture/src/mf_encoder.cpp lines 941-994, or correct all three statements.

• electron/native/README.md#L88-L88: remove "the shared bridge texture" from the list of automatic degrade conditions, or state that a bridge failure stops the recording.
• technical-documentation/architecture/recording.md#L72-L72: remove "no shared keyed-mutex texture" from the "degrades to the CPU one on its own at every step" list, or state the exception.
• electron/native/wgc-capture/src/mf_encoder.h#L32-L37: drop the claim that a driver which refuses shared keyed-mutex textures "records exactly as it did before the path existed", or qualify it.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@electron/native/README.md` at line 88, The documentation incorrectly claims
shared keyed-mutex texture creation falls back to CPU encoding, although
MFEncoder::convertBgraTextureToNv12 creates it after initialization and failure
stops recording. Update electron/native/README.md:88-88,
technical-documentation/architecture/recording.md:72-72, and
electron/native/wgc-capture/src/mf_encoder.h:32-37 to remove that fallback claim
or explicitly state that bridge creation failure stops recording; no code change
is requested.

🎯 Functional Correctness | 🔴 Critical | ⚡ Quick win

webcamActive is always false here, so inline webcam PiP silently loses the overlay.

webcamActive is initialized to false at line 531 and set to true only at line 977, after encoder.initialize() at line 621. At line 617 it is therefore always false, and (!webcamActive || writeSeparateWebcam) is always true.

A recording with webcamEnabled: true and no webcamOutputPath then selects the DXGI path. Line 842 passes webcamFrame only in the CPU branch, so the picture-in-picture overlay is never composed. The recording succeeds and reports videoInput: "dxgi-nv12", so nothing signals the missing webcam.

Use the configuration value that is already resolved at this point.

     encoderOptions.useDxgiInput =
         !config.preferSoftwareEncoder &&
-        (!webcamActive || writeSeparateWebcam) &&
+        (!config.webcamEnabled || writeSeparateWebcam) &&
         readEnvInt("OPENSCREEN_WGC_DISABLE_DXGI_INPUT", 0) == 0;

config.webcamEnabled is already cleared at line 551 when webcam initialization fails, and writeSeparateWebcam is assigned at line 558, so both are final by line 615.

Verify with a webcam recording on real Windows hardware: CI runs only on Linux. Based on coding guidelines: "Native capture changes require a manual smoke test on real macOS or Windows, because CI runs only on Linux."

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@electron/native/wgc-capture/src/main.cpp` around lines 610 - 618, Update the
encoderOptions.useDxgiInput condition to use the resolved config.webcamEnabled
value instead of webcamActive, while preserving writeSeparateWebcam and the
software-encoder and environment-variable checks. Keep inline webcam PiP on the
CPU path when webcamEnabled is true and no separate webcam output is configured;
verify with a real Windows webcam recording.

Source: Coding guidelines

🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

Release the DXGI resources in finalize() as well.

releaseDxgiPipeline() is the only place that resets the new DXGI state, and initialize() calls it only on a fallback. On a successful GPU recording the resources live until the MFEncoder destructor runs.

finalize() (lines 1321-1338) resets stagingTexture_, context_, and device_, then calls MFShutdown(). Two consequences follow:

• videoSampleAllocator_ and dxgiDeviceManager_ are Media Foundation objects that stay alive across MFShutdown().
• captureDevice_ and captureContext_ keep the WGC D3D11 device alive after finalize(), so session.stop() in main.cpp no longer releases the last reference.

Call releaseDxgiPipeline() from finalize() before MFShutdown(), and reset captureDevice_/captureContext_ there too.

    stagingTexture_.Reset();
    releaseDxgiPipeline();
    captureContext_.Reset();
    captureDevice_.Reset();
    context_.Reset();
    device_.Reset();
    MFShutdown();

Verify the teardown order on real Windows hardware: CI runs only on Linux. Based on coding guidelines: "Native capture changes require a manual smoke test on real macOS or Windows, because CI runs only on Linux."

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@electron/native/wgc-capture/src/mf_encoder.cpp` around lines 729 - 748,
Update MFEncoder::finalize() to call releaseDxgiPipeline() before MFShutdown(),
then reset captureContext_ and captureDevice_ before completing teardown.
Preserve the existing stagingTexture_, context_, and device_ cleanup, and verify
the destruction order with a real Windows hardware smoke test.

Source: Coding guidelines

🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift

Bridge-texture setup failure ends the recording; it does not degrade to the CPU path.

This block creates the shared keyed-mutex texture, opens it on the encoder device, and builds the input view. It runs on the first frame, long after initialize() configured the sink writer for NV12. Every failure here returns Nv12ConvertResult::Failed, which captureDxgiSample reports as false, which main.cpp (lines 845-849) turns into encodeFailed plus a stop request.

The documented contract says the opposite. mf_encoder.h lines 32-36 state that "a driver that refuses shared keyed-mutex textures records exactly as it did before the path existed", and both electron/native/README.md and technical-documentation/architecture/recording.md list "no shared keyed-mutex texture" as an automatic degrade. No degrade is possible at this point.

Move the bridge creation into initializeDxgiPipeline(), where a failure still falls back to the CPU path. initialize() already knows width_, height_, and the BGRA format that captureDxgiSample validates, so the descriptor does not need a WGC frame.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@electron/native/wgc-capture/src/mf_encoder.cpp` around lines 941 - 994, Move
the shared bridge-texture setup currently guarded by captureBridgeTexture_ into
initializeDxgiPipeline(), using width_, height_, and the validated BGRA format
to construct its descriptor without a WGC frame. Ensure every creation, mutex,
shared-resource, encoder-open, and input-view failure causes initialization to
select the existing CPU fallback rather than returning Nv12ConvertResult::Failed
from captureDxgiSample; keep per-frame processing limited to using the
already-initialized bridge resources.

🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

Classify only a timeout as Contended.

AcquireSync returns WAIT_TIMEOUT for a busy bridge, but it also returns hard errors such as DXGI_ERROR_DEVICE_REMOVED, E_FAIL, and WAIT_ABANDONED. FAILED(...) maps all of them to Nv12ConvertResult::Contended.

A permanently broken bridge then skips every remaining frame. main.cpp counts each skip and keeps going, so the recording ends with exit code 0, a recording-stopped event, and an MP4 that holds almost no frames. Treat only WAIT_TIMEOUT as recoverable.

-    if (FAILED(captureBridgeMutex_->AcquireSync(0, acquireTimeoutMs))) {
-        return Nv12ConvertResult::Contended;
-    }
+    const HRESULT acquireHr = captureBridgeMutex_->AcquireSync(0, acquireTimeoutMs);
+    if (acquireHr == static_cast<HRESULT>(WAIT_TIMEOUT)) {
+        return Nv12ConvertResult::Contended;
+    }
+    if (!succeeded(acquireHr, "Acquire capture bridge")) {
+        return Nv12ConvertResult::Failed;
+    }

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@electron/native/wgc-capture/src/mf_encoder.cpp` around lines 996 - 1001,
Update the AcquireSync result handling in the capture-side mutex path to return
Nv12ConvertResult::Contended only when the result is WAIT_TIMEOUT. Propagate or
classify all other failure results, including WAIT_ABANDONED and device errors,
as non-recoverable using the existing error-handling contract.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Report the active writer operation.

Line 1271 sets encodeStage_ before writerMutex_ is acquired. If writeAudio owns the mutex in IMFSinkWriter::WriteSample, a waiting video thread overwrites the stage with "write-sample". writeAudio does not report an audio write stage. The shutdown watchdog can report the wrong blocking operation.

Set the video stage after acquiring writerMutex_. Set and clear an audio stage around the audio WriteSample call.

 bool MFEncoder::submitVideoSample(IMFSample* sample) {
-    encodeStage_ = "write-sample";
     std::scoped_lock writerLock(writerMutex_);
     if (!sinkWriter_ || finalized_) {
         encodeStage_ = "idle";
         return false;
     }
+    encodeStage_ = "write-sample";
     const bool written = succeeded(sinkWriter_->WriteSample(videoStreamIndex_, sample), "WriteSample");
     encodeStage_ = "idle";
     return written;
 }

 bool MFEncoder::writeAudio(...) {
     std::scoped_lock writerLock(writerMutex_);
     // Validate and construct sample.
-    return succeeded(sinkWriter_->WriteSample(audioStreamIndex_, sample.Get()), "WriteSample(audio)");
+    encodeStage_ = "write-audio";
+    const bool written =
+        succeeded(sinkWriter_->WriteSample(audioStreamIndex_, sample.Get()), "WriteSample(audio)");
+    encodeStage_ = "idle";
+    return written;
 }

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@electron/native/wgc-capture/src/mf_encoder.cpp` around lines 1271 - 1278,
Move the video `encodeStage_ = "write-sample"` assignment in the video write
path to after `writerMutex_` is acquired, keeping the existing idle cleanup. In
the audio write method, set an audio-specific stage immediately after locking
`writerMutex_` and clear it after the audio `WriteSample` call, including the
early-return path, so the shutdown watchdog reports the operation that currently
owns the writer.